
/*
This file is part of MJIN2.

Copyright (C) 2012-2013 Opensource Game Studio

This software is provided 'as-is', without any express or implied
warranty.  In no event will the authors be held liable for any damages
arising from the use of this software.

Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:

1. The origin of this software must not be misrepresented; you must not
   claim that you wrote the original software. If you use this software
   in a product, an acknowledgment in the product documentation would be
   appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
   misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
*/

#ifndef MJIN2_REG_EXP_H
#define MJIN2_REG_EXP_H

#include <mjin2/Common.h>
#include <mjin2/TypeDefs.h>

namespace mjin2
{

namespace priv
{
class RegExp;
}

//! Regular expression matcher.
/*! Example:
 *  \code
 *  RegExp re("\n|\t");
 *  StringList sl;
 *  sl.push_back("A dog\nand cat");
 *  sl.push_back("A bird,\ta mole");
 *  sl.push_back("A man without a cat");
 *  for (StringList::iterator it = sl.begin(); it != sl.end(); ++it)
 *      if (re.match(*it))
 *          std::cout << *it << std::endl;
 *  \endcode
 *  The example will only print the first two lines.
 *  The third one doesn't match the specified regular expression.
 */
class RegExp
{
        DISALLOW_COPY_AND_ASSIGN(RegExp);
    public:
        RegExp() throw ();
        //! You can also set pattern later with setPattern call.
        //! \throw if cannot set the pattern.
        RegExp(const String &pattern,
               bool         caseSensitive = true) throw (Exception);
        ~RegExp() throw ();

        //! Try to match provided string.

        //! \param string String to match against the pattern.
        //! \param matchList If provided, collects subpatterns/substrings,
        //! i.e., (\\d+) things like that.
        //! \return true if match succeeded, false otherwise.
        bool match(const String &string,
                   StringList   *matchList = 0) throw (Exception);
        //! Pattern and case sensitivity are those set for this RegExp instance.
        String replace(const String &string,
                       const String &replacement,
                       bool         all = true) throw (Exception);
        //! Pattern and case sensitivity are those set for this RegExp instance.
        StringList split(const String &string) throw (Exception);
        //! Set pattern for RegExp instance.
        void setPattern(const String &pattern,
                        bool         caseSensitive = true) throw (Exception);

    private:
        priv::RegExp *mD;
};

} // namespace mjin2

#endif // MJIN2_REG_EXP_H

